Node / rns-mirrors / Reticulum-Go.git / files / docs / en / architecture.md

Displaying Rendered • View raw • Download

This page explains how Reticulum-Go is structured, describing layers, control flow, persistence, and deployment patterns.

For package-level detail see Package map. For wire-level behavior see Transport and Interfaces.

Reticulum-Go follows the same conceptual layers as Python Reticulum:

T282828

Each layer depends downward only. Interfaces know nothing about application names. Destinations do not open raw sockets.

The daemon is the long-running process most operators deploy. On startup it:

1. Loads configuration from T383838~/.reticulum-go/config (or T383838--config)

2. Creates a T383838node.Node which owns transport and interfaces

3. Starts transport and registers each enabled interface

4. Optionally attaches to a shared instance (share_instance)

5. Applies the runtime sandbox (T383838pkg/sandbox) unless disabled

6. Optionally starts the control API on localhost

7. Handles T383838SIGHUP on Unix to hot-reload interface blocks

Shutdown on T383838SIGINT or T383838SIGTERM stops interfaces and flushes path persistence where configured.

Node is the embedder-facing orchestration type. It wires:

• T383838transport.Transport for routing

• T383838interfaces.Interface instances from config

• T383838sharedinstance.Instance when sharing one Reticulum process on a host

• Optional T383838discovery.InterfaceDiscovery when discover_interfaces is enabled

• Network lifecycle hooks (OnNetworkAvailable, OnNetworkLost, RefreshPaths, ReloadInterfaces)

Library authors typically construct T383838node.New(cfg) and call T383838Start() rather than reimplementing transport registration.

Transport is the routing engine. It maintains:

• A path table mapping destination hashes to next-hop interface and hop count

• Registered destinations and their packet receivers

• Link table entries for established sessions

• Announce handlers and ingress or egress rate limits

• Optional on-disk persistence for paths and known destinations

Every interface registers a callback that feeds inbound bytes into T383838Transport.HandlePacket.

Interfaces translate between Reticulum packets and a physical medium. They handle:

• IFAC mask and unmask on ingress and egress (T383838pkg/common)

• HDLC framing for TCP and backbone clients

• Reconnect loops for TCP, UDP (opt-in), I2P, and backbone clients

• Platform-specific socket options (IPv6 preference, bind addresses)

Factory entry point: T383838interfaces.NewFromConfigWithContext.

When T383838share_instance = yes, only one Reticulum process on a host should own the real interfaces. Other processes connect as clients over TCP or a Unix socket and multiplex packets through the owner. This mirrors Python behavior and uses msgpack RPC compatible with RNS 1.3.4 layouts.

Go CLI tools such as rgostatus dial this RPC. On Linux, Python rnsd defaults to a Unix abstract socket unless T383838shared_instance_type = tcp. Setup for mixed Go and Python tooling is in CLI utilities.

The daemon persists ratchets, identity blobs, destination tables, and related artifacts under T383838~/.reticulum-go/storage/. Library embedders can use the same paths or keep tables in memory with inmemorypathtable and inmemoryknowndestinations.

Set T383838in_memory_storage = yes (or T383838RETICULUM_IN_MEMORY_STORAGE=1) for fully ephemeral operation: no transport identity file, no blackhole directory, no split-resource staging on disk, and no T383838~/.reticulum-go bootstrap. Empty ConfigPath with no T383838RETICULUM_STORAGE_PATH also stays off disk. Soft caps (T383838max_in_memory_paths, T383838max_in_memory_known_destinations, T383838max_packet_hashlist, T383838soft_memory_limit) always bound RAM for the path table, known destinations, and packet hash filter. The split-resource byte budget still applies only under explicit in-memory storage.

T282828

Key functions (for code navigation):

• T383838BaseInterface.ProcessIncoming in T383838pkg/interfaces/interface.go

• T383838Transport.HandlePacket in T383838pkg/transport/transport.go

• T383838Transport.handleTransportPacket for data context routing

T282828

If no path exists, transport may emit path requests according to configuration and watched destinations.

• Each interface runs its own read loop (or shares a backbone hub poller). Stream interfaces (TCP, QUIC, VSOCK, WebTransport, I2P, Local, Pipe, backbone hub) read 64 KiB at a time. HDLC still splits frames at the packet MTU.

• Transport HandlePacket copies the frame then hands it to a fixed worker pool (T383838max_packet_handlers, default 512). Overflow sheds under dos_protection instead of spawning more goroutines.

• Links run session goroutines for keepalive, request/response, and channel outlets.

• Hot reload takes reloadMu on Node to swap interfaces without tearing down unrelated state.

Backbone I/O can consolidate many TCP sockets behind one epoll, kqueue, or iouring hub (T383838pkg/backbone). Configure with backboneio in T383838[reticulum].

One T383838reticulum-go process with local interfaces. Suitable for gateways, radios, and servers.

T282828

Multiple processes, one interface owner. Useful when a single radio or tunnel must be shared.

T282828

A Go service links T383838pkg/node directly. No daemon. The service loads config, starts Node, and registers destinations in-process.

T383838reticulum-wasm compiles transport and a WebSocket interface. JavaScript calls T383838reticulum.init, connect, announce, and related functions exposed by T383838pkg/wasm.

Non-Go applications talk HTTP and WebSocket to T383838pkg/controlapi on localhost while the daemon owns transport. See Control API.

Native hosts link T383838librns.so and call T383838include/rns.h. Same stack as T383838pkg/node, no separate daemon. Linux first. Odin hosts can use T383838bindings/odin. See librns.

T383838microvm/ packages a static guest rootfs and a host vsock bridge for nested or isolated nodes. Default networking keeps clearnet on the host and pipes the guest over Firecracker vsock. See Firecracker microvm.

Cryptography is centralized in T383838pkg/cryptography and T383838pkg/identity. IFAC adds an optional outer authentication layer on interface frames. The runtime sandbox limits filesystem and privilege exposure after startup. Neither replaces correct key handling or network segmentation.

See Cryptography and Security.

Adding a new interface type or changing on-wire layouts requires coordinated updates across implementations and crossref vectors.

• IP routing or DNS replacement

• Built-in application protocols (LXMF, MF, and RRC live in reticulum-go-protocols. NomadNet and similar stay in other projects)

• RNode firmware or serial radio drivers

• Post-quantum algorithms

Those may integrate over Reticulum destinations and links but are out of scope for this repository.